## Quick Start

### TDengine TSDB CLI

To easily check the status of TDengine TSDB and perform various ad-hoc database queries, TDengine TSDB provides a command-line interface. To enter the TDengine CLI, simply execute `taos` (on Linux/Mac) or `taos.exe` (on Windows) in your terminal. The prompt appears as:

```sql
taos>
```

In the TDengine TSDB CLI, you can use SQL commands to create or delete databases and tables, as well as perform data insertion and query operations. Each SQL statement executed in the terminal must end with a semicolon (;). For example:

```sql
CREATE DATABASE demo;
USE demo;
CREATE TABLE t (ts TIMESTAMP, speed INT);
INSERT INTO t VALUES ('2019-07-15 00:00:00', 10);
INSERT INTO t VALUES ('2019-07-15 01:00:00', 20);
SELECT * FROM t;
```

```sql
           ts            |    speed    |
========================================
 2019-07-15 00:00:00.000 |          10 |
 2019-07-15 01:00:00.000 |          20 |

Query OK, 2 row(s) in set (0.003128s)
```

You can also use the TDengine TSDB CLI to monitor system status, manage users, and perform administrative tasks.

The CLI and client drivers can be installed separately on other machines. For more details, see [TDengine CLI Reference](https://docs.tdengine.com/tdengine-reference/tools/tdengine-cli/).

### Data Ingestion

taosBenchmark is a tool designed to evaluate TDengine’s performance in data ingestion, querying, and subscription. It can simulate data generated by numerous devices, allowing flexible configuration of database, supertable, tag columns, data columns, subtable counts, record counts, data intervals, number of threads, and whether to include out-of-order data.

To use taosBenchmark, ensure that TDengine is installed and running, and then execute the following command:

```shell
taosBenchmark -y
```

This automatically creates a database named `test` containing a supertable named `meters`. Within the supertable, 10,000 subtables named d0 through d9999 are generated, each containing 10,000 records. Each record has four fields: `ts` (timestamp), `current`, `voltage`, and `phase`, with timestamps ranging from `2017-07-14 10:40:00 000` to `2017-07-14 10:40:09 999`. Each table also contains two tags: `location` and `groupId`, where `groupId` ranges from `1` to `10` and `location` includes cities in California such as `California.Campbell` and `California.Cupertino`.

After executing the `taosBenchmark` command, the system quickly writes 100 million records. The time required depends on your hardware, but on an average server, this process typically takes only a few seconds.

To customize testing parameters such as table counts or record numbers, taosBenchmark provides a wide range of options. To see all available parameters, run the following command:

```shell
taosBenchmark --help
```

For detailed usage instructions, see [taosBenchmark Reference](https://docs.tdengine.com/tdengine-reference/tools/taosbenchmark/).

### Data Querying

After inserting data with taosBenchmark, you can run the following queries in the TDengine CLI to verify query performance.

Count total records in the supertable `meters`:

```sql
SELECT COUNT(*) FROM test.meters;
```

Calculate the average, maximum, and minimum of all records:

```sql
SELECT AVG(current), MAX(voltage), MIN(phase) FROM test.meters;
```

Count records where location = `California.SanFrancisco`:

```sql
SELECT COUNT(*) FROM test.meters WHERE location = "California.SanFrancisco";
```

Query the average, maximum, and minimum for all records where `groupId` = `10`:

```sql
SELECT AVG(current), MAX(voltage), MIN(phase) FROM test.meters WHERE groupId = 10;
```

Aggregate table d1001 in 10-second intervals and compute averages, maxima, and minima:

```sql
SELECT _wstart, AVG(current), MAX(voltage), MIN(phase) FROM test.d1001 INTERVAL(10s);
```

:::note

In the above query, the pseudocolumn `_wstart` represents the start time of each aggregation window.

:::

### TDengine TSDB Explorer

TDengine TSDB Explorer is a web-based interface that allows you to manage and interact with TDengine directly from your browser.

To use TDengine TSDB Explorer, access its address in a web browser. The default port is 6060. For example, if TDengine is running locally, visit `http://localhost:6060`.

Enter your username and password and click Login. The default username is `root` and password `taosdata`.

If you have not logged in to TDengine TSDB Explorer before, you must register first. Enter your name and email address and click **Get verification code**. Then enter the verification code sent to your email address and click **Submit**.

After logging in, the **Explorer** page is displayed, where you can view databases, supertables, subtables, and run SQL queries.

On the **Programming** page, you can view client library examples for various programming languages, all of which can be executed directly via copy/paste.

The **Tools** page lists visualization tools that integrate with TDengine such as Grafana and Power BI. You can follow the on-screen guidance to create dashboards and reports easily.

Click the **?** icon in the upper-right corner of the interface to access the TDengine documentation. This is installed locally and does not require an internet connection.

### Integration with Grafana

Grafana is a popular open-source platform for data visualization and monitoring. TDengine integrates seamlessly with Grafana to create dashboards and alert systems, all without writing a single line of code. The example below uses smart meter data generated by taosBenchmark to create a panel that displays current fluctuations.

#### Prerequisites

- Install and start Grafana (version 7.5 or above is supported).
- Insert test data using the following command, which creates a supertable meters in the test database with 100 subtables, each containing 1,000 records starting from one hour ago:

   ```bash
   taosBenchmark --start-timestamp=$(date --date="1 hours ago" +%s%3N) \
     --time-step=1000 --records=1000 \
     --tables=100 --answer-yes
   ```

#### Install the Grafana Plugin

Communication between Grafana and TDengine is handled via the TDengine Datasource plugin.

On Linux, you can install the plugin by running the following command:

```bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/taosdata/grafanaplugin/master/install.sh)"
```

For other platforms, refer to the plugin [installation guide](https://github.com/taosdata/grafanaplugin/blob/master/INSTALLATION.md).

After installation, restart the Grafana service:

```bash
sudo systemctl restart grafana-server.service
```

#### Create a Connection

In Grafana, go to **Connections** > **Add new connection**, search for `TDengine`, and click **Add new data source**.

Configure the data source as follows:

- TDengine Host: Enter the address and port of your taosAdapter. For local setups, use `http://localhost:6041`.
- TDengine Authentication: Use the database’s username and password authentication (default: root/taosdata).

Click **Save & test**. If you see the message ``TDengine Data source is working``, the connection is successful.

#### Create a Dashboard

Select **Dashboards** > **New** and click **Add a new panel**.  Choose the TDengine data source that you configured earlier.

In the `Input SQL` field, enter the following query and click `Apply`. This displays the average variation of the `current` column:

```sql
SELECT _wstart AS ts, avg(voltage) AS voltage, avg(phase) AS phase FROM test.meters
WHERE groupid =1 and ts > $from AND ts < $to interval($interval) fill(null)
```

For more details, see [Grafana](https://docs.tdengine.com/third-party-tools/visualization/grafana/).

### Zero-Code Data Ingestion

TDengine TSDB can ingest data from various sources, including PI System, OPC, InfluxDB, MQTT, Kafka, CSV, MySQL, PostgreSQL, Oracle, and MongoDB.

The following example shows how to create an MQTT data ingestion task to subscribe to data from an MQTT broker and write it into TDengine.

#### Configure Basic Task Information

1. In a web browser, access TDengine TSDB Explorer.
1. From the main menu on the left, select **Data In**.
1. On the **Data In Task** tab, click **+ Add Source** to open the task configuration page.
1. Configure the MQTT task as follows:
   - Name: Enter a unique name for the data ingestion task.
   - Type: Select **MQTT**.
   - Agent: Leave this field blank.
   - Target: Click **+ Create Database**, enter `test-mqtt` as the name, and click **Create**.
1. Configure the connection and authentication:
   - MQTT Host: `broker.emqx.io`
   - Port: `1883`
   - TLS Verification: **Disable**
   - Username/Password: Leave these fields blank.
1. Configure MQTT protocol settings:
   - MQTT Protocol Version: 3.1
   - Client ID: Enter a unique ID for the data ingestion task.
   - Topics QoS Config: Must be separated by two colons, e.g. `tdengine-topic1::0`
   - Retain the default value for all other settings.
1. Click **Check Connectivity**. If the message ``Your data source is reachable`` appears, the connection is successful.
1. Configure payload transformation:
   1. Enter the following JSON sample representing smart meter readings (voltage, current, and phase) for meter ID 1 in Beijing:

   ```json
   { "id": 1, "current": 10.42, "phase": 1.38, "voltage":200, "groupid": 7, "location": "beijing" }
   ```

   1. Click the Preview icon on the right to preview parsing results.
   1. Under Mapping, create a supertable with the following schema:

      Columns:

      | Data Type    | Name     |
      | ------------ | -------- |
      | TIMESTAMP    | ts       |
      | INT          | id       |
      | DOUBLE       | current  |
      | DOUBLE       | phase    |
      | INT          | voltage  |

      Tags:

      | Data Type    | Name     |
      | ------------ | -------- |
      | INT          | groupid  |
      | VARCHAR(128) | location |

      After creating and selecting the supertable, click Submit.

1. Your task is now displayed in the **Data In Task** list. When its status changes to **Running**, data from the MQTT topic will be consumed and written into TDengine TSDB automatically.

#### Send Test Data

You can use the MQTT client tool MQTTX to send test data. For more information, see [the documentation](https://docs.emqx.com/en/emqx/latest/getting-started/getting-started.html).

Use the same broker and topic configuration as your MQTT task:

- Broker Address: broker.emqx.io
- Port: 1883
- Topic: tdengine-topic1
- Sample Data:

   ```json
   { "id": 1, "current": 10.42, "phase": 1.38, "voltage":200, "groupid": 7, "location": "beijing" }
   ```

#### Verify Data

After sending test data, you can check whether it has been successfully written to TDengine TSDB. In TDengine TSDB Explorer, run the following SQL statement:

```sql
SELECT * FROM `test-mqtt`.`meters`;
```

If data is returned, it confirms successful ingestion.

You can also view the task’s running status, ingestion rate, and error logs on the Data In page.

### What to Do Next

After completing this quick start, you can continue exploring TDengine’s advanced capabilities and features.
